Description
Manual connections provide a means of manipulating nodal objects from standard user code and as such are similar to conventional semaphore or mutex handles. They can be owned by any active object (threads, methods, call-backs or circuits) and objects in their event trees can be accessed through their access/member functions. References to manual connections are returned by appropriate access functions (see Access Functions).
Methods are executed when events arrive at their trigger connections and may not necessarily own any manual connections. Circuits can own manual connections which are typically used to initialize stores and/or semaphores. Threads however, must own at least one manual (or reference) connection. Call back functions cannot own manual connections but can use interface objects instead.
Manual Connection Types
Manual connections are created by the translator and references to them returned by their access functions. Manual connection 'types' are determined by their providing object types. CDL supports the following manual connection types, each with their own member functions;
CLIP::AstManCxn
Arbitrated store, manual connection
CLIP::TstManCxn
Transient store, manual connection
CLIP::CsmManCxn
Counting semaphore, manual connection
CLIP::LsmManCxn
Logical semaphore, manual connection
CLIP::ClxManCxn
Collector, manual connection
CLIP::CpxManCxn
Competer, manual connection
CLIP::DbxManCxn
Distributor, manual connection
CLIP::DmxManCxn
Demultiplexor, manual connection
CLIP::MpxManCxn
Multiplexor, manual connection
CLIP::RdxManCxn
Reducer, manual connection
CLIP::SpxManCxn
Splitter, manual connection
Manual Connection Attributes
Most manual connection attributes are fixed at connection time, but timeouts, keys, and rules, can be specified at runtime as arguments to connection member functions, and connections can be re-used for read/write/update or signal/request combinations. Connection attributes fall into two categories. Firstly there are those attributes that apply to the provider, and different providers will require different attributes. Secondly there are those attributes that apply to the consumer, and these are common to all manual connections. So each particular provider type/consumer type pair will have a particular set of attributes. The nodal objects section of this documentation lists each nodal object's particular providing and/or consuming attributes.
All manual connections have the following attributes;
Timeout
This attribute determines whether the connection will poll or block (see Connection Timeout). This attribute can be specified at runtime.
Signature
This attribute is a string that describes the mapping from elements in the consumer, to elements in the provider. See Connection Signature.
Name
This attribute determines the connection's 'name' which is used to construct access function names (see Connection Names).
Dimspec
This attribute determines the dimensionality of the manual connection array. By default, this will provide the owning active element with one connection for each provider element (see 'mapped connections' below).
Repeat Count
This attribute determines the number of connections that are made between each element of the of the manual connection and its providing element. If the repeat count is greater then one, then connection's access functions will have an 'extra' dimension (see example below).
The following example code writes to a transient store and could be executed from a method, circuit or thread. In this example, the OpenWrite call will use the static attributes (key and timeout) that were set by the Blueprint editor;
Aux1_CTst1Cxn().OpenWrite(); // Wait for write access with static timeout and key
Aux1_CTst1Cxn().Record().Construct(); // Construct the store's record (data object)
Populate( Aux1_CTst1Cxn().Record() ); // Call user defined code to populate the store's record
Aux1_CTst1Cxn().Close(); // Close the connection
In this example, the OpenWrite call will over-ride the connection's key and timeout attributes;
Aux1_CTst1Cxn().OpenWrite( k, // Wait for write access with explicit key and timeout
CLP_WAIT );
Aux1_CTst1Cxn().Record().Construct(); // Construct the store's record (data object)
Populate( Aux1_CTst1Cxn().Record() ); // Call user defined code to populate the store's record
Aux1_CTst1Cxn().Close(); // Close the connection
Example
See Manual Connections.